#%RAML 1.0
title: Calendar
version: v4.0
baseUri: https://github.com/folio-org/mod-calendar

documentation:
  - title: mod-calendar API
    content: This module provides a backend for the calendar functionalities

types:
  OpeningPeriod: !include schemas/Opening.json
  OpeningCollection: !include schemas/OpeningCollection.json
  OpeningHoursCollection: !include schemas/OpeningHoursCollection.json
  errors: !include raml-util/schemas/errors.schema

traits:
  language: !include raml-util/traits/language.raml
  pageable: !include raml-util/traits/pageable.raml
  validate: !include raml-util/traits/validation.raml

resourceTypes:
  collection: !include raml-util/rtypes/collection.raml
  collection-item: !include raml-util/rtypes/item-collection.raml
  get-only: !include raml-util/rtypes/get-only.raml

/calendar:
  /periods:
    type:
      get-only:
        exampleCollection: !include examples/opening_hours_collection_get.json
        schema: OpeningHoursCollection

    get:
      is: [pageable]
      queryParameters:
        servicePointId:
          displayName: servicePointId
          type: string
          description: "Filter for service point. In case of parameter absence all service point will be included in response."
          required: false
        startDate:
          displayName: startDate
          type: string
          description: "Filter for start date (ISO 8601 date format). The parameter is inclusive."
          example: "2018-05-01"
          required: false
        endDate:
          displayName: endDate
          type: string
          description: "Filter for end date (ISO 8601 date format). The parameter is inclusive."
          example: "2018-05-31"
          required: false
        includeClosedDays:
          displayName: includeClosedDays
          type: boolean
          description: "In case of true all days will have value even if it is closing time or not"
          required: false
          default: true
        actualOpening:
          displayName: actualOpening
          type: boolean
          description: "In case of true exceptional openings are overriding regular opening and in this case regular opening is not included in the response"
          required: false
          default: true
      description: "List actual opening hours including exceptions for custom date range.
                    Mainly used by calendar display and provides opening information for loan rules.
                    The response contains only the openings closed times are not included."
      responses:
        200:
          body:
            application/json:
              type: OpeningHoursCollection
        404:
          description: "Not found. There is no service point with the given ID"
        500:
          description: "Internal server error"

    /{servicePointId}:
      /period:
        type:
          collection:
            exampleCollection: !include examples/opening_collection_get.json
            schemaCollection: OpeningCollection
            schemaItem: OpeningPeriod
            exampleItem: !include examples/opening_get.json
        get:
          queryParameters:
            withOpeningDays:
              displayName: withOpeningDays
              type: boolean
              description: "Include opening days in response."
              required: false
              default: false
            showPast:
              displayName: showPast
              type: boolean
              description: "Include past openings in response."
              required: false
              default: false
            showExceptional:
              displayName: showExceptional
              type: boolean
              description: "Filter for exceptional library hours periods."
              required: false
              default: false
          description: "List library hours period. The default response contains the period names and its dates."
          responses:
            200:
              body:
                application/json:
                  type: OpeningCollection
            404:
              description: "Not found. There is no service point with the given ID"
            500:
              description: "Internal server error"
        post:
          is: [validate]
          body:
            application/json:
              type: OpeningPeriod
          description: "Saves the new library period"
          responses:
            201:
              description: "Returns with the created period"
              body:
                application/json:
                  type: OpeningPeriod
            400:
              description: "Bad request"
            422:
              description: "Unprocessable Entity"
            500:
              description: "Internal server error"

        /{periodId}:
          type:
            collection-item:
              exampleItem: !include examples/opening_get.json
              schema: OpeningPeriod
          get:
            description: "List opening hours for given periodId."
            responses:
              200:
                body:
                  application/json:
                    type: OpeningPeriod
              404:
                description: "Library hours period or service point with the given ID is not found"
              500:
                description: "Internal server error"
          delete:
            description: Delete Opening hours by Id
            responses:
              204:
               description: "Library hours period was deleted successfully"
              404:
                description: "Library hours period or service point with the given ID is not found"
              400:
                description: "Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
              500:
                description: "Internal server error, e.g. due to misconfiguration"
          put:
            is: [validate]
            description: "Update library period by periodId"
            body:
              application/json:
                  type: OpeningPeriod
            responses:
              204:
                description: "Library period successfully updated"
              404:
                description: "Library period id or service point with the given ID is not found"
              422:
                description: "Unprocessable Entity"
              400:
                description: "Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
              500:
                description: "Internal server error, e.g. due to misconfiguration"

      /calculateopening:
        get:
          is: [language]
          queryParameters:
            requestedDate:
              displayName: requestedDate
              description: "requested date"
              example: "2019-01-31"
              type: string
              required: true
          description: "This endpoint helps to calculate due date. The response contains three openings: the requested day,
                        next and previous dates openings which are closest to the requested day."
          responses:
            200:
              body:
                application/json:
                  schema: OpeningPeriod
            400:
              body:
                text/plain:
              description: "Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
            404:
              body:
                text/plain:
              description: "Not found"
            500:
              description: "Internal server error"
              body:
                text/plain:
